'\" et
.TH PTHREAD_EXIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
pthread_exit
\(em thread termination
.SH SYNOPSIS
.LP
.nf
#include <pthread.h>
.P
void pthread_exit(void *\fIvalue_ptr\fP);
.fi
.SH DESCRIPTION
The
\fIpthread_exit\fR()
function shall terminate the calling thread and make the value
.IR value_ptr
available to any successful join with the terminating thread. Any
cancellation cleanup handlers that have been pushed and not yet popped
shall be popped in the reverse order that they were pushed and then
executed. After all cancellation cleanup handlers have been executed,
if the thread has any thread-specific data, appropriate destructor
functions shall be called in an unspecified order. Thread termination
does not release any application visible process resources, including,
but not limited to, mutexes and file descriptors, nor does it perform
any process-level cleanup actions, including, but not limited to,
calling any
\fIatexit\fR()
routines that may exist.
.P
An implicit call to
\fIpthread_exit\fR()
is made when a thread other than the thread in which
\fImain\fR()
was first invoked returns from the start routine that was used to
create it. The function's return value shall serve as the thread's
exit status.
.P
The behavior of
\fIpthread_exit\fR()
is undefined if called from a cancellation cleanup handler or
destructor function that was invoked as a result of either an implicit
or explicit call to
\fIpthread_exit\fR().
.P
After a thread has terminated, the result of access to local (auto)
variables of the thread is undefined. Thus, references to local
variables of the exiting thread should not be used for the
\fIpthread_exit\fR()
.IR value_ptr
parameter value.
.P
The process shall exit with an exit status of 0 after the last thread
has been terminated. The behavior shall be as if the implementation
called
\fIexit\fR()
with a zero argument at thread termination time.
.SH "RETURN VALUE"
The
\fIpthread_exit\fR()
function cannot return to its caller.
.SH ERRORS
No errors are defined.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
The normal mechanism by which a thread terminates is to return from the
routine that was specified in the
\fIpthread_create\fR()
call that started it. The
\fIpthread_exit\fR()
function provides the capability for a thread to terminate without
requiring a return from the start routine of that thread, thereby
providing a function analogous to
\fIexit\fR().
.P
Regardless of the method of thread termination, any
cancellation cleanup handlers that have been pushed and not yet popped
are executed, and the destructors for any existing thread-specific data
are executed. This volume of POSIX.1\(hy2017 requires that cancellation cleanup handlers be
popped and called in order. After all cancellation cleanup handlers have
been executed, thread-specific data destructors are called, in an
unspecified order, for each item of thread-specific data that exists in
the thread. This ordering is necessary because cancellation cleanup
handlers may rely on thread-specific data.
.P
As the meaning of the status is determined by the application (except
when the thread has been canceled, in which case it is
PTHREAD_CANCELED),
the implementation has no idea what an illegal status value is, which
is why no address error checking is done.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIexit\fR\^(\|)",
.IR "\fIpthread_create\fR\^(\|)",
.IR "\fIpthread_join\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<pthread.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
